Taeluf.com

Markdown Verbs

Markdown Verbs are essentially just functions you can write in your .src.md files. (I'm not sure why I call them verbs, but I do)

Also see: @see_files(docs/Templates.md; Templates, docs/ASTTemplates.md; AST Templates; docs/Configuration.md; Configuration; docs/Extensions.md; Extensions)

Docs

  • Calling Markdown Verbs
  • Create Markown Verbs
  • Built-in verbs
  • Import/Export

Calling Markdown Verbs

This must be in a .src.md file in your configured dir.src.

Syntax:

@verb_name(arg1, arg2)

Notes:

  • The output of the @function_call() will replace the @function_call()
  • Arguments cannot contain commas (,) or closing parenthesis ())
  • Place a backslash (\) after the @ sign to prevent the function from being called, like @\see(some_file). (Alternatively, place a zero width non-joiner after the @, but then people won't know it's there when they copy+paste your example.)
  • If a verb (function) does not exist, then the function call will remain, unchanged

Create Markdown Verbs

  1. Create a bootstrap file (Configured via file.bootstrap)
    • or implement the bootstrap() method in your extension
  2. Call $scrawl->add_md_verb('verb_name', $callable) (use $this->add_md_verb() in your bootsrap file)
  3. Implement the callable: function($arg1, $arg2){ echo "Anything"; }

Now calls to @verb_name(arg1, arg2) will be replaced with "Anything" (the output of your callable)

Built-in verbs

@template(Scrawl/ShortMdVerbsList)

@template(Scrawl/MdVerbs)

Import/Export

There are two ways to export, and either export can be printed in a markdown file via:

\@import(Key)

@export(Key)

@export(Key) exports all text in a docblock above the @export(). Each line of the export is trimmed and the asterisks (*) are removed.

Example:

<?php

/**
* Get an array of books with the partial title matching
*
* @param $like_title string
* @return array of Book objects
* @export(get_books)
*/
function get_books(string $like_title): array{}

Then you could \@import(get_books) in your documentation.

@export_start(Key) & @export_end(Key)

Use this to export all text between the two export tags.

Example (from @link(liaison)'s tests):

<?php

$lia = new \Lia();
$package = new \Lia\Package($lia, 'test');
new \Lia\Addon\Resources($package);

// @export_start(ResourcesAddon.AddResources)
$resources = \Lia\Addon\Resources::from($lia); // your Liaison instance

// Files will be concatenated and added to a singular css file
$private_dir = dirname(__DIR__,2).'/input/private/resources/';
$resources->addFile($private_dir.'/undeliverable-styles.css');
$resources->addFile($private_dir.'/undeliverable-scripts.js');

// URLs will be added as `<link>` and `<script>` tags and added to the HTML head
$resources->addURL('/resources/page-layout.css'); // deliverable on your site
$resources->addURL('https://cdn.example.com/my-namespace/dancing-bear.js'); // external file
// @export_end(ResourcesAddon.AddResources)

Then Liaison documentation uses \@import(ResourcesAddon.AddResources) in its documentation to print the above code.